Copyright ã1995 by NeXT Computer, Inc.  All Rights Reserved.

Form

Inherits From:	Matrix : Control : View : Responder : Object

Declared In:	appkit/Form.h

Class Description

A Form is a Matrix that contains titled entries into which a user can type data values.   Here's an example:

,

Entries are indexed starting with zero at the top.  Each item in the Form, including the title, is a FormCell.  A mouse click a FormCell (that is, on the title or in the entry area) starts text editing in that entry.  If the user presses the Return or Enter key while editing an entry, the action of the entry is sent to the target of the entry, orÐif the entry doesn't have an actionÐthe Form sends its action ito its target.  If the user presses the Tab key, the next entry in the Form is selected; if the user presses Shift-Tab, the previous entry is selected.

For more information, see the FormCell and Matrix class specifications.  

Instance Variables

None declared in this class.

Method Types

Setting Form's Cell class	+ setCellClass:

Initializing a Form	- initFrame:

Laying out the Form	- addEntry:
- addEntry:tag:target:action:
- insertEntry:at:
- insertEntry:at:tag:target:action:
- removeEntryAt:
- setInterline:

Assigning a tag	- setTag:at:

Finding indices	- findIndexWithTag:
- selectedIndex

Modifying graphic attributes	- setBezeled:
- setBordered:
- setFont:
- setTitleFont:
- setTextFont:
- setTitleAlignment:
- setTextAlignment:

Setting item titles	- setTitle:at:
- titleAt:

Setting item values	- setDoubleValue:at:
- doubleValueAt:
- setFloatValue:at:
- floatValueAt:
- setIntValue:at:
- intValueAt:
- setStringValue:at:
- stringValueAt:

Editing text	- selectTextAt:

Resizing the Form	- calcSize
- setEntryWidth:
- sizeTo::
- sizeToFit

Displaying	- drawCellAt:

Target and action	- setAction:at:
- setTarget:at:

Class Methods

setCellClass:

+ setCellClass:classId

Configures the Form class to use instances of classId for its Cells.  classId should be the id of a subclass of FormCell, obtained by sending the class message to either the FormCell subclass object or to an instance of that subclass.  The default Cell class is FormCell.  Returns self.

ªCreating New Controlsº in the Control class specification has more information on how to safely set the Cell class used by a subclass of Control.  

See also:  - initFrame:

Instance Methods

addEntry:

- addEntry:(const char *)title

Adds a new item with aString as the title to the bottom of the receiving Form and returns the FormCell created.  The new FormCell has no tag, target, or action, but is enabled and editable.  Does not redraw the Form even if autodisplay is on.

See also:  - addEntry:tag:target:action:

addEntry:tag:target:action:

- addEntry:(const char *)title
tag:(int)anInt
target:anObject
action:(SEL)aSelector

Adds a new item with aString as the title to the bottom of the receiving Form and returns the FormCell created.  The FormCell's tag is set to anInt, it action to aSelector, and its target to anObject.  The new FormCell is enabled and editable.  Does not redraw the Form even if autodisplay is on.

See also:  - addEntry:

calcSize

- calcSize

Calculates the size and layout of the Form based on the sizes of its Cells and their title portions.  Your code should invoke this method before drawing if it modifies any of the Cells in the Form in such a way that the size of the Cells or the size of the title part of the Cells has changed.  This method is automatically invoked before any drawing is done after a setTitle:at:, setFont:, setBezeled: or some other similar Form method has been invoked.

See also:  - validateSize: (Matrix)

doubleValueAt:

- (double)doubleValueAt:(int)index

Returns the value of the entry at position index as a double-precision floating point number.  Form does not override Control's doubleValue method; your code should never use that method with a Form.

See also:  - setDoubleValue:at:, - floatValueAt:, - intValueAt:, - stringValueAt:, - doubleValue (Control)

drawCellAt:

- drawCellAt:(int)index

 Displays the FormCell at the specified index in the Form.

findIndexWithTag:

- (int)findIndexWithTag:(int)aTag

Returns the index of the Cell with the corresponding tag, -1 otherwise.

See also:  - findCellWithTag: (Matrix)

floatValueAt:

- (float)floatValueAt:(int)index

Returns the value of the entry at position index as a single-precision floating point number.  Form does not override Control's floatValue method; your code should never use that method with a Form.

See also:  - setFloatValue:at:, - doubleValueAt:, - intValueAt:, - stringValueAt:, - floatValue (Control)

initFrame:

- initFrame:(const NXRect *)frameRect

Initializes and returns the receiver, a new instance of Form, with default parameters in the given frame.  The new Form has no entries.  Newly created entries will have the following default characteristics:  titles will be right aligned, text will be left justified with bezeled borders, entry background color will be white, text color black, fonts will be the user's chosen system font in 12.0, the interline spacing will be 1.0, and the actions will be NULL.  This method is the designated initializer for Form; override it if you create a subclass of Form that performs its own initialization.

Note that Form doesn't override the Matrix class's designated initializers initFrame:mode:cellClass:numRows:numCols: or initFrame:mode:prototype:numRows:numCols:.  Don't use those methods to initialize a new instance of Form.  

See also:  - initFrame: (Matrix), - initFrame:mode:cellClass:numRows:numCols:, - initFrame:mode:prototype:numRows:numCols:

insertEntry:at:

- insertEntry:(const char *)title at:(int)index

Inserts an item with the title title at position index in the Form.  The item at the top of the form has an index of  0.  The new FormCell has no tag, target, or action.  Returns the FormCell used to implement the entry.  Returns the newly inserted FormCell.  Does not redraw the Form even if autodisplay is on.

See also:  - insertEntry:at:tag:target:action:, - addEntry:, - addEntry:tag:target:action:, - removeEntryAt:

insertEntry:at:tag:target:action:

- insertEntry:(const char *)title
at:(int)index
tag:(int)anInt
target:anObject
action:(SEL)aSelector

Inserts a new entry with the given title at position index.  The tag, target, and action of the corresponding entry are set to the given values.  Returns the newly inserted FormCell.  Does not redraw the Form even if autodisplay is on.

See also:  - insertEntry:at:, - addEntry:, - addEntry:tag:target:action:, - removeEntryAt:

intValueAt:

- (int)intValueAt:(int)index

Returns the value of the entry at position index as an integer.  Form does not override Control's intValue method; your code should never use that method with a Form.

See also:  - setIntValue:at:, - doubleValueAt:, - floatValueAt:, - stringValueAt:, - intValue (Control)

removeEntryAt:

- removeEntryAt:(int)index

If index is a valid position in the Form, removes the entry there and frees it.  Note that if you use Matrix's removeRowAt:andFree: method to remove an entry, the widths of the titles in the entries will not be readjusted; your code should use this method instead.  Does not redraw the Form even if autodisplay is on.  Returns self.

See also:  - addEntry:, - insertEntry:at:

selectTextAt:

- selectTextAt:(int)index

If index is a valid position in the Form, begins text editing on the item at that position.  Returns the FormCell selected.

selectedIndex

- (int)selectedIndex

Returns the index of the currently selected entry if any, -1 otherwise.  The currently selected entry is the one being edited or, if none of the entries is being edited, then it's the entry that was last edited.

setAction:at:

- setAction:(SEL)aSelector at:(int)index

Sets the action of the FormCell at position index to aSelector.  Returns self.

See also:  - action (ActionCell), - setTarget:at:

setBezeled:

- setBezeled:(BOOL)flag

If flag is YES, all Cells in the Form are set to show a bezel around their editable text and are redrawn; if flag is NO, Cells in the Form have no bezel.  A bezel is mutually exclusive with a border, and invoking this method with NO as the argument will not remove a border.  Returns self.

See also:  - isBezeled (Cell), - setBordered:

setBordered:

- setBordered:(BOOL)flag

If flag is YES, all Cells in the Form are set to show a 1-pixel black border around their editable text and are redrawn; if flag is NO, Cells in the Form have no border.  A border is mutually exclusive with a bezel, and invoking this method with NO as the argument will not remove a bezel.  Returns self.

See also:  - isBordered (Cell), - setBezeled:

setDoubleValue:at:

- setDoubleValue:(double)aDouble at:(int)index

Sets the value of the item at position index to aDouble and redraws that item.  Form does not override Control's setDoubleValue: method; your code should never use that method with a Form.

See also:  - doubleValueAt:, - setFloatValue:at:, - setIntValue:at:, - setStringValue:at:, - setDoubleValue: (Control)

setEntryWidth:

- setEntryWidth:(NXCoord)width

Sets the width of all the entries (including the title part).  Doesn't redisplay the Form.  You should invoke sizeToFit after invoking this method.  Returns self.

See also:  - sizeToFit

setFloatValue:at:

- setFloatValue:(float)aFloat at:(int)index

Sets the value of the item at position index to aFloat and redraws that item.  Form does not override Control's setFloatValue: method; your code should never use that method with a Form.

See also:  - floatValueAt:, - setDoubleValue:at:, - setIntValue:at:, - setStringValue:at:, - setFloatValue: (Control)

setFont:

- setFont:fontObject

Sets the Font used to draw both the titles and the editable text in the Form.  It's generally best to keep the title Font and the text Font the same (or at least the same size); therefore, this method is preferred to setTitleFont: and setTextFont:.  Redraws the Form if autodisplay is on.  Returns self.

See also:  - setTitleFont:, - setTextFont:

setIntValue:at:

- setIntValue:(int)anInt at:(int)index

Sets the value of the item at position index to anInt and redraws that item.  Form does not override Control's setIntValue: method; your code should never use that method with a Form.

See also:  - intValueAt:, - setDoubleValue:at:, - setFloatValue:at:, - setStringValue:at:, - setIntValue: (Control)

setInterline:

- setInterline:(NXCoord)spacing

Sets the space between items in the Form to spacing.  Does not redraw the matrix even if autodisplay is on.  Returns self.

setStringValue:at:

- setStringValue:(const char *)aString at:(int)index

Sets the value of the item at position index to aString and redraws that item.  Form does not override Control's setStringValue: method; your code should never use that method with a Form.

See also:  - stringValueAt:, - setFloatValue:at:, - setDoubleValue:at:, - setStringValue:at:, - setStringValue: (Control)

setTag:at:

- setTag:(int)anInt at:(int)index

Sets the tag of the FormCell at position index to anInt.  Returns self.

See also:  - tag (ActionCell)

setTarget:at:

- setTarget:anObject at:(int)index

Sets the target of the FormCell at position index to anObject.  Returns self.

See also:  - target (ActionCell), - setAction:at:

setTextAlignment:

- setTextAlignment:(int)mode

Sets the alignment mode for the editable text in the Form.  mode can be one of three constants:  NX_LEFTALIGNED, NX_CENTERED, or NX_RIGHTALIGNED.  The default is left aligned.  Redraws the Form if autodisplay is on, and returns self.

See also:  - setTitleAlignment:

setTextFont:

- setTextFont:fontObject

Sets the Font used to draw the editable text in the Form to fontObject.  Redraws the Form if autodisplay is on, and returns self.

See also:  - setFont:, - setTitleFont:

setTitle:at:

- setTitle:(const char *)aString at:(int)index

Changes the title of the entry at position index to aString.

See also:  - titleAt:

setTitleAlignment:

- setTitleAlignment:(int)mode

Sets the alignment mode for titles in the Form.  mode can be one of three constants:  NX_LEFTALIGNED, NX_CENTERED, or NX_RIGHTALIGNED.  The default is right aligned.  Redraws the Form if autodisplay is on, and returns self.

See also:  - setTextAlignment:

setTitleFont:

- setTitleFont:fontObject

Sets the Font used to draw the titles in the Form. to fontObject  Redraws the Form if autodisplay is on, and returns self.

See also:  - setFont:, - setTextFont:

sizeTo::

- sizeTo:(NXCoord)width :(NXCoord)height

Resizes the entry width to reflect width, then resizes the Form to width and height.  Doesn't redraw the Form.  Returns self.

See also:  - sizeToFit

sizeToFit

- sizeToFit

Adjusts the width of the Form so that it's the same as the width of the entries.  Adjusts the height of the Form so that it will exactly contain all the Cells.  Doesn't redraw the Form.  Returns self.

See also:  - sizeTo::, - setEntryWidth:

stringValueAt:

- (const char *)stringValueAt:(int)index

Returns the value of the entry at position index as a string.  Form does not override Control's stringValue method; your code should never use that method with a Form.

See also:  - setStringValue:at:, - doubleValueAt:, - floatValueAt:, - intValueAt:, - stringValue (Control)

titleAt:

- (const char *)titleAt:(int)index

Returns the title of the entry at position index.

See also:  - setTitle:at: